home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga News 95
/
Amiga News 95.iso
/
dpat
/
dpat49
/
reqtools.lzh
/
ReqTools
/
doc
/
reqtools.doc
next >
Wrap
Text File
|
1991-12-28
|
51KB
|
1,257 lines
TABLE OF CONTENTS
reqtools.library/rtAllocRequestA
reqtools.library/rtChangeReqAttrA
reqtools.library/rtEZRequestA
reqtools.library/rtFileRequestA
reqtools.library/rtFontRequestA
reqtools.library/rtFreeFileList
reqtools.library/rtFreeReqBuffer
reqtools.library/rtFreeRequest
reqtools.library/rtGetLongA
reqtools.library/rtGetStringA
reqtools.library/rtGetVScreenSize
reqtools.library/rtPaletteRequestA
reqtools.library/rtReqHandlerA
reqtools.library/rtScreenToFrontSafely
reqtools.library/rtSetReqPosition
reqtools.library/rtSetWaitPointer
reqtools.library/rtSpread
reqtools.library/rtAllocRequestA reqtools.library/rtAllocRequestA
NAME rtAllocRequestA()
req = rtAllocRequestA (type, taglist);
APTR rtAllocRequestA (ULONG, struct TagItem *);
D0 D0 A0
req = rtAllocRequest (type, tag1,...);
APTR rtAllocRequest (ULONG, Tag,...);
DESCRIPTION
Allocates a requester structure for you in a future compatible manner.
This is the only way to properly allocate a rtFileRequester,
rtFontRequester or rtReqInfo structure. The structure will be
initialized for you.
Use rtFreeRequest() to free the requester structure when you no longer
need it.
INPUTS
type - type of structure to allocate, currently RT_REQINFO,
RT_FILEREQ or RT_FONTREQ.
taglist - pointer to array of tags (currently always NULL).
TAGS
no tags defined yet
RESULT
req - pointer to the requester allocated or NULL if no memory.
BUGS
none known
SEE ALSO
rtFreeRequest()
reqtools.library/rtChangeReqAttrA reqtools.library/rtChangeReqAttrA
NAME rtChangeReqAttrA()
[long =] rtChangeReqAttrA (req, taglist);
[LONG] rtChangeReqAttrA (APTR, struct TagItem *);
A1 A0
[long =] rtChangeReqAttr (req, tag1,...);
[LONG] rtChangeReqAttr (APTR, Tag,...);
DESCRIPTION
Change requester attributes with supplied taglist. This is the only
correct way to change the attributes listed below.
The return code from rtChangeReqAttrA() should be ignored unless stated
otherwise.
INPUTS
req - pointer to requester.
taglist - pointer to array of tags.
TAGS
for the file requester:
RTFI_Dir - (char *)
Name of new directory to position file requester
in. The requester's buffer will be deallocated.
RTFI_MatchPat - (char *)
New pattern string to match files on.
RTFI_AddEntry - (BPTR)
THIS *MUST* BE THE LAST TAG (just before TAG_END)!
Tagdata must hold a lock on a file or directory
you want to add to the file requester's buffer.
The lock should have been obtained using Lock(),
and you must unlock this lock yourself.
It is your responsability to make sure the file
or directory is indeed in the directory the file
requester is in.
If the entry is already in the file requester's
buffer it will simply be updated.
It is harmless to call this function if the
requester's buffer is not initialized.
rtChangeReqAttr() will return a boolean to
indicate success or failure (out of memory).
RTFI_RemoveEntry - (char *)
Name of file or directory you want to remove from
the file requester's buffer.
It is your responsability to make sure the file
or directory is indeed in the directory the file
requester is in.
It is harmless to call this function if the
requester's buffer is not initialized.
for the font requester:
RTFO_FontName - (char *)
Set the name of the currently selected font.
RTFO_FontHeight - (UWORD)
Set the fontsize of the currently selected font.
RTFO_FontStyle - (UBYTE)
Set the style of the current font.
RTFO_FontFlags - (UBYTE)
Set the flags of the current font.
RESULT
none
BUGS
none known
SEE ALSO
dos.library/Lock()
reqtools.library/rtEZRequestA reqtools.library/rtEZRequestA
NAME rtEZRequestA()
ret = rtEZRequestA (bodyfmt, gadfmt, reqinfo, argarray, taglist);
ULONG rtEZRequestA
(char *, char *, struct rtReqInfo *, APTR, struct TagItem *);
D0 A1 A2 A3 A4 A0
ret = rtEZRequest (bodyfmt, gadfmt, reqinfo, taglist, arg1, arg2,...);
ULONG rtEZRequest
(char *, char *, struct rtReqInfo *, struct TagItem *,...);
ret = rtEZRequestTags(bodyfmt, gadfmt, reqinfo, argarray, tag1,...);
ULONG rtEZRequestTags(char *, char *, struct rtReqInfo *, APTR, Tag,...);
DESCRIPTION
This function puts up a requester for you and waits for a response from
the user. If the response is positive, this procedure returns TRUE.
If the response is negative, this procedure returns FALSE.
The function may also return an IDCMP flag or a value corresponding with
one of other possible responses (see below).
'gadfmt' may contain several possible responses. Seperate these
responses by a '|'. For example: "Yes|No", or 'Yes|Maybe|No". The
responses should be typed in the same order as they will appear on
screen, from left to right. There is no limit to the number of responses
other than the width of the screen the requester will appear on.
'bodyfmt' can contain newlines ('\n', ASCII 10). This will cause a new
line to be started (surprise, surprise :-).
You may also include 'printf' style formating codes. The format arguments
should be pointed to by 'argarray'.
You can use formatting codes in 'gadfmt' as well. The arguments for
this format string should follow the ones for 'bodyfmt'.
NOTE: The formatting is done by exec.library/RawDoFmt(), so be aware that
to display a 32-bit integer argument you must use "%ld", not "%d",
since RawDoFmt() is "word-oriented."
The second and third function use a variable number of arguments. These
functions can be found in 'reqtools[nb].lib'.
The second function has the RawDoFmt arguments as variable args, the
third the tags. If you need both this is what you can do:
...
{
ULONG tags[] = { RTEZ_ReqTitle, (ULONG)"mytitle", TAG_END };
rtEZRequest ("String, num: %s, %ld", NULL, "Ok",
(struct TagItem *)tags, "six", 6);
}
...
You can satisfy the requester with the following keyboard shortcuts:
'Y' or Left Amiga 'V' for a positive response,
ESC, 'N', 'R' or Left Amiga 'B' for a negative response.
If EZREQF_NORETURNKEY is _not_ set (see RTEZ_Flags below) the RETURN key
is also accepted as a shortcut for the positive response (can be changed
using RTEZ_DefaultResponse, see below). The response that will be
selected when you press RETURN will be printed in bold.
The EZREQF_LAMIGAQUAL flag should be used when you put up a requester
for a destructive action (e.g. to delete something). When it is set
the keyboard shortcuts are limited to Left Amiga 'V' and 'B' so it is
harder to accidently select something you will regret.
Note that the RETURN and ESC key remain active! To disable the RETURN
key use the EZREQF_NORETURNKEY flag. The ESC key cannot be disabled.
You may pass a NULL for 'gadfmt', but make sure you know what you are
doing. Passing a NULL opens an EZRequester with NO responses, just a
body text. This implies the user has no means of "answering" this
requester. You must therefore use the RT_IDCMPFlags tag to allow some
other events to end the requester (e.g. IDCMP_MOUSEBUTTONS,
IDCMP_INACTIVEWINDOW,...) or you must make use of the ReqHandler feature.
Using a requester handler you can end the requester by program control.
This way you can e.g. put up a requester before you start loading a file
and remove it after the file has been loaded. Do not pass an empty
string as 'gadfmt'!
'reqinfo' can be used to customize the requester. For greater control
use the tags listed below. The advantage of the rtReqInfo structure is
that it is global, where tags have to be specified each function call.
See libraries/reqtools.[hi] for a description of the rtReqInfo structure.
INPUTS
bodyfmt - requester body text, can be format string a la RawDoFmt().
gadfmt - text for gadgets (left to right, seperated by '|') or NULL.
argarray - pointer to array of arguments for format string(s).
reqinfo - pointer to a rtReqInfo structure allocated with
rtAllocRequest() or NULL.
taglist - pointer to a TagItem array.
TAGS
RT_Window - (struct Window *)
Window that will be used to find the screen to put the
requester on.
You *MUST* supply this if you are a task calling this
function and not a process! This is because tasks
don't have a pr_WindowPtr.
RT_IDCMPFlags - (ULONG)
Extra idcmp flags to return on. If one these IDCMP
flags causes the requester to abort the return code
will equal the flag in question.
RT_ReqPos - (ULONG)
One of the following:
REQPOS_POINTER - requester appears where the mouse
pointer is (default).
REQPOS_CENTERSCR - requester is centered on the
screen.
REQPOS_CENTERWIN - requester is centered in the
window (only works if the
pr_WindowPtr of your process is
valid or if you use RT_Window).
If RT_Window is NULL the
requester will be centered on
the screen.
REQPOS_TOPLEFTSCR - requester appears at the top left
of the screen.
REQPOS_TOPLEFTWIN - requester appears at the top left
of the window (only works if the
pr_WindowPtr of your process is
valid or if you use RT_Window).
The requester will always remain in the visible part of
the screen, so if you use the Workbench 2.0 ScreenMode
preferences editor to enlarge your Workbench screen and
you scroll around, the requester will always appear in
the part you can see.
REQPOS_CENTERSCR and REQPOS_TOPLEFTSCR also apply to
the visible part of the screen. So if you use one of
these the requester will be appear in the center or the
top left off what you can see of the screen as opposed
to the entire screen.
REQPOS_CENTERWIN and REQPOS_TOPLEFTWIN fall back to
REQPOS_CENTERSCR or REQPOS_TOPLEFTSCR respectively
when there is no parent window. So you can safely use
these without worrying about the existence of a window.
RT_LeftOffset - (ULONG)
Offset of left edge of requester relative to position
specified with RT_ReqPos (does not offset the requester
when RT_ReqPos is REQPOS_POINTER).
RT_TopOffset - (ULONG)
Offset of top edge of requester relative to position
specified with RT_ReqPos (does not offset the requester
when RT_ReqPos is REQPOS_POINTER).
RT_PubScrName - (char *)
Name of public screen requester should appear on. When
this tag is used the RT_Window tag will be ignored.
If the public screen is not found the requester will
open on the default public screen.
Only works on Kickstart 2.0! reqtools.library does
not check this, it is up to you *NOT* to use this tag
on Kickstart 1.3 or below!
Note that the 1.3 version of reqtools.library also
understands and supports this tag (on 2.0).
RT_Screen - (struct Screen *)
Address of screen to put requester on. You should
never use this, use RT_Window or RT_PubScrName.
RT_ReqHandler - (struct rtHandlerInfo **)
Using this tag you can start an "asynchronous"
requester. ti_TagData of the tag must hold the address
of a pointer variable to a rtHandlerInfo structure.
The requester will initialize this pointer and will
return immediately after its normal initialization.
The return code will not be what you would normally
expect. If the return code is _not_ equal to
CALL_HANDLER an error occured and you should take
appropriate steps. If the return code was CALL_HANDLER
everything went ok and the requester will still be up!
See the explanation for rtReqHandlerA() below for the
following steps you have to take.
RT_WaitPointer - (BOOL)
If this is TRUE the window calling the requester will
get a standard wait pointer set while the requester is
up. This will happen if you used the RT_Window tag or
if your process's pr_WindowPtr is valid. Note that
after the requester has finished your window will be
ClearPointer()-ed. If you used a custom pointer in
your window you will have to re-set it, or not use the
RT_WaitPointer tag and put up a wait pointer yourself.
Defaults to FALSE. It is advised you use this tag as
much as possible.
RTEZ_ReqTitle - (char *)
Title of requester window, default is "Request" unless
the requester has less than 2 responses, then the
default title is "Information".
RTEZ_Flags - (ULONG)
Flags for rtEZRequestA():
EZREQF_NORETURNKEY - turn off the RETURN key as
shorcut for positive response.
EZREQF_LAMIGAQUAL - keyboard shortcuts are limited
to Left Amiga 'V' and 'B', ESC
and RETURN.
EZREQF_CENTERTEXT - centers each line of body text
in the requester window. Useful
for about requesters.
RTEZ_DefaultResponse - (ULONG)
Response value that will be returned when the user
presses the return key. Will be ignored if the
EZREQF_NORETURNKEY flag is set. The text for this
response will be printed in bold. Default is 1.
RESULT
ret - 1 (TRUE) for leftmost (positive) response, then each consecutive
response will return 1 more, the rightmost (false) respons will
return 0 (FALSE), so 1,2,3,...,num-1,0 -- or idcmp flag.
NOTE
Automatically adjusts the requester to the screen's font.
rtEZRequestA() checks the pr_WindowPtr of your process to find the
screen to put the requester on.
BUGS
none known
SEE ALSO
exec.library/RawDoFmt(), rtReqHandlerA()
reqtools.library/rtFileRequestA reqtools.library/rtFileRequestA
NAME rtFileRequestA()
ret = rtFileRequestA (filereq, filename, title, taglist);
APTR rtFileRequestA
(struct rtFileRequester *, char *, char *, struct TagItem *);
D0 A1 A2 A3 A0
ret = rtFileRequest (filereq, filename, title, tag1,...);
APTR rtFileRequest (struct rtFileRequester *, char *, char *, Tag,...);
DESCRIPTION
Get a directory and filename(s), or just a directory from the user.
'filename' should point to an array of at least 108 chars. The filename
already in 'filename' will be displayed in the requester when it comes
up. When the requester returns 'filename' will probably have changed.
Setting certain flags may result in the calling of a caller-supplied
hook.
The hook will be called with A0 holding the address of your hook
structure (you may use the h_Data field to your own liking), A1 a pointer
to the requester structure ('req') and A2 a pointer to an array of
longwords ('param[]').
'param[0]' will hold the type of the hook, the rest (if any) depends on
that type.
'req' will point to the requester structure of the requester calling the
hook.
SAS/C users can define their function thus:
ULONG __asm __saveds hookfunc (register __a0 struct Hook *hook,
register __a2 APTR req,
register __a1 ULONG *param)
{
switch (param[0]) {
case REQHOOK_WILDFILE:
/* param[1] holds address of a FileInfoBlock */
...
return (skipit);
case REQHOOK_WILDFONT:
/* param[1] holds address of a TextAttr */
...
return (skipit);
default:
return (0);
}
}
Your hook should then be initialized like this:
hook->h_Entry = hookfunc;
/* in this case no need to initialize hook->h_SubEntry */
hook->h_Data = your_userdata_if_needed;
Succesively you should initialize the filereq->Hook field to point to
your hook. Note that there is no tag to set the hook!
You can also use a stub written in machine code to call
your function. (see 'utility/hooks.h')
Always check the hook's type to see why it is being called! You should
always return a value to tell the requester what to do after your hook
has finished. The return value of 0 has been reserved for "continue as
usual". So if your hook is called with a type other than the ones you
understand/handle return a 0!
Hook types ('param[0]') currently implemented for rtFileRequest():
REQHOOK_WILDFILE:
Set the FREQF_DOWILDFUNC flag to activate. The requester will
call your hook for each file in the directory.
'param[1]' will hold the address of a struct FileInfoBlock. If
your hook returns TRUE the file will be skipped an will not
appear in the requester.
Finally note that when you change your hook or your hook's behaviour
you _MUST_ purge the requester's buffer (using rtFreeReqBuffer())!
INPUTS
filereq - pointer to a struct rtFileRequester allocated with
rtAllocRequestA().
filename - pointer to an array of chars (must be 108 bytes big).
title - pointer to requester window title (null terminated).
taglist - pointer to a TagItem array.
TAGS
RT_Window - see rtEZRequestA()
RT_ReqPos - see rtEZRequestA()
RT_LeftOffset - see rtEZRequestA()
RT_TopOffset - see rtEZRequestA()
RT_PubScrName - see rtEZRequestA()
RT_Screen - see rtEZRequestA()
RT_ReqHandler - see rtEZRequestA()
RT_WaitPointer - see rtEZRequestA()
RT_DefaultFont - (struct TextFont *)
This tag allows you to specify the font to be used in
the requester when the screen font is proportional.
Default is GfxBase->DefaultFont.
RTFI_Flags - (ULONG)
Several flags:
FREQF_NOBUFFER - do _not_ use a buffer to remember
directory contents for the next
time rtFileRequestA() is used.
FREQF_MULTISELECT - allow multiple files to be
selected. rtFileRequestA() will
return a pointer to a rtFileList
structure which will contain all
selected files.
Use rtFreeFileList() to free the
memory used by this file list.
FREQF_SELECTDIRS - set this flag if you wish to
enable the selecting of dirs as
well as files. You *must* also
set FREQF_MULTISELECT.
Directories will be returned
together with files in rtFileList,
but with StrLen equal to -1.
If you need the length of the
directory's name use strlen().
FREQF_SAVE - Set this if you are using the
requester to save or delete
something. Double-clicking will
be disabled so it is harder to
make a mistake and select the
wrong file. If the user enters a
non-existent directory in the
string gadget, a requester will
appear asking if the directory
should be created.
FREQF_NOFILES - Set this if you want to use the
requester to allow the user to
select a directory rather than a
file. Ideal for getting a
destination directory.
May be used with FREQF_MULTISELECT
and FREQF_SELECTDIRS.
FREQF_PATGAD - When this is set a pattern gadget
will be added to the requester.
FREQF_DOWILDFUNC - Call req->Hook for each entry in
the directory.
Note that there is no tag to set
the hook. You must initialize
the req->Hook field with a pointer
to a valid hook structure.
See above for more information on
the calling of hooks.
RTFI_Height - (ULONG)
Suggested height of file requester window.
RTFI_OkText - (char *)
Replacement text for "Ok" gadget, max 6 characters long.
RESULT
ret - TRUE if the user selected a file (check 'filereq->Dir' for the
directory and 'filename' for the filename) or FALSE if the
requester was canceled -- or a pointer to a struct rtFileList
(if FREQF_MULTISELECT was used).
NOTE
Automatically adjusts the requester to the screen's font.
If the screen's font is proportional the default font will be used.
If the requester got too big for the screen because of a very large font,
the topaz.font will be used.
rtFileRequest() checks the pr_WindowPtr of your process to find the
screen to put the requester on.
BUGS
none known
SEE ALSO
reqtools.library/rtFontRequestA reqtools.library/rtFontRequestA
NAME rtFontRequestA()
bool = rtFontRequestA (fontreq, title, taglist);
BOOL rtFontRequestA (struct rtFontRequester *, char *, struct TagItem *);
D0 A1 A3 A0
bool = rtFontRequest (fontreq, title, tag1,...);
BOOL rtFontRequest (struct rtFontRequester *, char *, Tag,...);
DESCRIPTION
Let the user select a font and a style (optional).
Setting certain flags may result in the calling of a caller-supplied
hook. See rtFileRequest() for more information on the calling of this
hook.
Hook types ('param[0]') currently implemented for rtFontRequest():
REQHOOK_WILDFONT:
Set the FREQF_DOWILDFUNC flag to activate. The requester will
call your hook for each font in the system's font list.
'param[1]' will hold the address of a struct TextAttr. If your
hook returns TRUE the font will be skipped.
Finally note that when you change your hook or your hook's behaviour
you _MUST_ purge the requester's buffer (using rtFreeReqBuffer())!
INPUTS
fontreq - pointer to a struct rtFontRequester allocated with
rtAllocRequestA().
title - pointer to requester window title (null terminated).
taglist - pointer to a TagItem array.
TAGS
RT_Window - see rtEZRequestA()
RT_ReqPos - see rtEZRequestA()
RT_LeftOffset - see rtEZRequestA()
RT_TopOffset - see rtEZRequestA()
RT_PubScrName - see rtEZRequestA()
RT_Screen - see rtEZRequestA()
RT_ReqHandler - see rtEZRequestA()
RT_WaitPointer - see rtEZRequestA()
RT_DefaultFont - (struct TextFont *)
This tag allows you to specify the font to be used in
the requester when the screen font is proportional.
Default is GfxBase->DefaultFont.
RTFO_Flags - (ULONG)
Several flags:
FREQF_NOBUFFER - do not buffer the font list
for subsequent calls to
rtFontRequestA().
FREQF_FIXEDWIDTH - only display fixed-width fonts.
FREQF_COLORFONTS - display color fonts also.
FREQF_CHANGEPALETTE - change the screen's palette
to match that of a selected
color font.
FREQF_LEAVEPALETTE - leave the palette as it is
when exiting rtFontRequestA()
Useful in combination with
FREQF_CHANGEPALETTE.
FREQF_SCALE - allow fonts to be scaled
when they don't exist in the
requested size.
(works on Kickstart 2.0 only,
has no effect on 1.2/1.3).
FREQF_STYLE - include gadgets so the user
may select the font's style.
FREQF_DOWILDFUNC - Call req->Hook for each font.
Note that there is no tag to
set the hook. You must
initialize the req->Hook
field with a pointer to a
valid hook structure.
See rtFileRequest() for more
information on the calling of
this hook.
RTFO_Height - (ULONG)
Suggested height of font requester window.
RTFO_OkText - (char *)
Replacement text for "Ok" gadget. Maximum 6 chars.
(7 is still ok, but not esthetically pleasing)
RTFO_SampleHeight - (ULONG)
Height of font sample display in pixels (default 24).
RTFO_MinHeight - (ULONG)
Minimum font size displayed.
RTFO_MaxHeight - (ULONG)
Maximum font size displayed.
RESULT
bool - TRUE if the user selected a font (freq->Attr holds the font),
FALSE if the requester was canceled.
NOTE
Automatically adjusts the requester to the screen's font.
If the screen's font is proportional the default font will be used.
If the requester got too big for the screen because of a very large font,
the topaz.font will be used.
rtFontRequest() checks the pr_WindowPtr of your process to find the
screen to put the requester on.
BUGS
none known
SEE ALSO
reqtools.library/rtFreeFileList reqtools.library/rtFreeFileList
NAME rtFreeFileList()
rtFreeFileList (filelist);
void rtFreeFileList (struct rtFileList *);
A0
DESCRIPTION
Frees a filelist returned by rtFileRequest() when the FREQF_MULTISELECT
flag was set. Call this after you have scanned the filelist and you no
longer need it.
INPUTS
filelist - pointer to rtFileList structure, returned by rtFileRequest()
(may be NULL).
RESULT
none
BUGS
none known
SEE ALSO
rtFileRequest()
reqtools.library/rtFreeReqBuffer reqtools.library/rtFreeReqBuffer
NAME rtFreeReqBuffer()
rtFreeReqBuffer (req);
void rtFreeReqBuffer (APTR);
A1
DESCRIPTION
Frees the buffer associated with 'req'. In case of a file requester this
function will deallocate the directory buffer, in case of a font
requester the font list.
It is safe to call this function for requesters that have no buffer, so
you may call this for all requesters to free as much memory as possible.
INPUTS
req - pointer to requester.
RESULT
none
BUGS
none known
SEE ALSO
rtFileRequest(), rtFontRequest()
reqtools.library/rtFreeRequest reqtools.library/rtFreeRequest
NAME rtFreeRequest()
rtFreeRequest (req);
void rtFreeRequest (APTR);
A1
DESCRIPTION
Free requester structure previously allocated by rtAllocRequestA().
This will also free all buffers associated with the requester, so there
is no need to call rtFreeReqBuffer() first.
INPUTS
req - pointer to requester (may be NULL).
RESULT
none
BUGS
none known
SEE ALSO
rtAllocRequestA()
reqtools.library/rtGetLongA reqtools.library/rtGetLongA
NAME rtGetLongA()
ret = rtGetLongA (&longvar, title, reqinfo, taglist);
ULONG rtGetLongA (ULONG *, char *, struct rtReqInfo *, struct TagItem *);
D0 A1 A2 A3 A0
ret = rtGetLong (&longvar, title, reqinfo, tag1,...);
ULONG rtGetLong (ULONG *, char *, struct rtReqInfo *, Tag,...);
DESCRIPTION
Puts up a requester to get a signed long (32-bit) number from the user.
'reqinfo' can be used to customize the requester. For greater control
use the tags listed below. The advantage of the rtReqInfo structure is
that it is global, where tags have to be specified each function call.
See libraries/reqtools.[hi] for a description of the rtReqInfo structure.
INPUTS
&longvar - address of long (32 bit!) variable to hold result.
title - pointer to null terminated title of requester window.
reqinfo - pointer to a rtReqInfo structure allocated with
rtAllocRequest() or NULL.
taglist - pointer to a TagItem array.
TAGS
RT_Window - see rtEZRequestA()
RT_IDCMPFlags - see rtEZRequestA()
RT_ReqPos - see rtEZRequestA()
RT_LeftOffset - see rtEZRequestA()
RT_TopOffset - see rtEZRequestA()
RT_PubScrName - see rtEZRequestA()
RT_Screen - see rtEZRequestA()
RT_ReqHandler - see rtEZRequestA()
RT_WaitPointer - see rtEZRequestA()
RTGL_Min - (ULONG)
Minimum allowed value. If the user tries to enter a
smaller value the requester will refuse to accept it.
RTGL_Max - (ULONG)
Maximum allowed value, higher values are refused.
RTGL_Width - (ULONG)
Width if requester window in pixels. This is only a
suggestion. rtGetLongA() will not go below a
certain width.
RTGL_ShowDefault - (BOOL)
If this is TRUE (default) the value already in
'longvar' will be displayed in the requester when it
comes up. If set to FALSE the requester will be empty.
RESULT
ret - TRUE if user entered a number, FALSE if not. If one of your idcmp
flags caused the requester to end 'ret' will hold this flag.
NOTE
'longvar' will NOT change if the requester is aborted.
Automatically adjusts the requester to the screen's font.
rtGetLongA() checks the pr_WindowPtr of your process to find the
screen to put the requester on.
BUGS
none known
SEE ALSO
reqtools.library/rtGetStringA reqtools.library/rtGetStringA
NAME rtGetStringA()
ret = rtGetStringA (buffer, maxchars, title, reqinfo, taglist);
ULONG rtGetStringA
(UBYTE *, ULONG, char *, struct rtReqInfo *, struct TagItem *);
D0 A1 D0 A2 A3 A0
ret = rtGetString (buffer, maxchars, title, reqinfo, tag1,...);
ULONG rtGetString (UBYTE *, ULONG, char *, struct rtReqInfo *, Tag,...);
DESCRIPTION
Puts up a string requester to get a line of text from the user.
The string present in 'buffer' upon entry will be displayed, ready to
be edited.
'reqinfo' can be used to customize the requester. For greater control
use the tags listed below. The advantage of the rtReqInfo structure is
that it is global, where tags have to be specified each function call.
See libraries/reqtools.[hi] for a description of the rtReqInfo structure.
INPUTS
buffer - pointer to buffer to hold characters entered.
maxchars - maximum number of characters that fit in buffer (EX-cluding
the 0 to terminate the string !).
title - pointer to null terminated title of requester window.
reqinfo - pointer to a rtReqInfo structure allocated with
rtAllocRequest() or NULL.
taglist - pointer to a TagItem array.
TAGS
RT_Window - see rtEZRequestA()
RT_IDCMPFlags - see rtEZRequestA()
RT_ReqPos - see rtEZRequestA()
RT_LeftOffset - see rtEZRequestA()
RT_TopOffset - see rtEZRequestA()
RT_PubScrName - see rtEZRequestA()
RT_Screen - see rtEZRequestA()
RT_ReqHandler - see rtEZRequestA()
RT_WaitPointer - see rtEZRequestA()
RTGS_Width - (ULONG)
Width of requester window in pixels. This is only a
suggestion. rtGetStringA() will not go below a certain
width.
RTGS_AllowEmpty - (BOOL)
If RTGS_AllowEmpty is TRUE an empty string will also
be accepted and returned. Defaults to FALSE, meaning
that if the user enters an empty string the requester
will be canceled.
RESULT
ret - TRUE if user entered something, FALSE if not. If one of your idcmp
flags caused the requester to end 'ret' will hold this flag.
NOTE
The contents of the buffer will NOT change if the requester is aborted.
Automatically adjusts the requester to the screen's font.
rtGetStringA() checks the pr_WindowPtr of your process to find the
screen to put the requester on.
BUGS
none known
SEE ALSO
reqtools.library/rtGetVScreenSize reqtools.library/rtGetVScreenSize
NAME rtGetVScreenSize()
rtGetVScreenSize (screen, widthptr, heightptr);
ULONG rtGetVScreenSize (struct Screen *, ULONG *, ULONG *);
D0 A0 A1 A2
DESCRIPTION
Use this function to get the size of the visible portion of a screen.
The value returned by rtGetVScreenSize() can be used for vertical
spacing. It will be larger for interlaced and productivity screens.
Using this number for spacing will assure your requester will look
good on an interlaced and a non-interlaced screen.
Current return codes are 2 for non-interlaced and 4 for interlaced.
These values may change in the future, don't depend on them too much.
They will in any case remain of the same magnitude.
INPUTS
screen - pointer to the screen.
widthptr - address of an ULONG variable to hold the width.
heightptr - address of an ULONG variable to hold the height.
RESULT
none
NOTE
This function is for the advanced reqtools user.
BUGS
SEE ALSO
reqtools.library/rtPaletteRequestA reqtools.library/rtPaletteRequestA
NAME rtPaletteRequestA()
color = rtPaletteRequestA (title, reqinfo, taglist);
LONG rtPaletteRequestA (char *, struct rtReqInfo *, struct TagItem *);
D0 A2 A3 A0
color = rtPaletteRequest (title, reqinfo, tag1,...);
LONG rtPaletteRequest (char *, struct rtReqInfo *, Tag,...);
DESCRIPTION
Put up a palette requester so the user can change the screen's colors.
The colors are changed in the viewport of the screen the requester will
appear on, so that is where you will find them after the palette
requester returns.
The selected color is returned, so you can also use this requester to let
the user select a color.
'reqinfo' can be used to customize the requester. For greater control
use the tags listed below. The advantage of the rtReqInfo structure is
that it is global, where tags have to be specified each function call.
See libraries/reqtools.[hi] for a description of the rtReqInfo structure.
INPUTS
title - pointer to requester window title (null terminated).
reqinfo - pointer to a rtReqInfo structure allocated with
rtAllocRequest() or NULL.
taglist - pointer to a TagItem array.
TAGS
RT_Window - see rtEZRequestA()
RT_ReqPos - see rtEZRequestA()
RT_LeftOffset - see rtEZRequestA()
RT_TopOffset - see rtEZRequestA()
RT_PubScrName - see rtEZRequestA()
RT_Screen - see rtEZRequestA()
RT_ReqHandler - see rtEZRequestA()
RT_WaitPointer - see rtEZRequestA()
RT_DefaultFont - (struct TextFont *)
This tag allows you to specify the font to be used in
the requester when the screen font is proportional.
Default is GfxBase->DefaultFont.
RTPA_Color - (ULONG)
Initially selected color of palette. Default is 1.
RESULT
color - the color number of the selected color or -1 if the user
canceled the requester.
NOTE
Automatically adjusts the requester to the screen's font.
If the screen's font is proportional the default font will be used.
If the requester got too big for the screen because of a very large font,
the topaz.font will be used.
rtPaletteRequestA() checks the pr_WindowPtr of your process to find the
screen to put the requester on.
BUGS
none known
SEE ALSO
reqtools.library/rtReqHandlerA reqtools.library/rtReqHandlerA
NAME rtReqHandlerA()
ret = rtReqHandlerA (handlerinfo, sigs, taglist);
ULONG rtReqHandlerA (struct rtHandlerInfo *, ULONG, struct TagItem *);
D0 A1 D0 A0
ret = rtReqHandler (handlerinfo, sigs, tag1,...);
ULONG rtReqHandler (struct rtHandlerInfo *, ULONG, Tag,...);
DESCRIPTION
This function should be called if you used the RT_ReqHandler tag with a
requester function.
The requester you used the tag with will have returned immediately after
its initialization and will have initialized a pointer to a rtHandlerInfo
structure for you.
You should now do the following:
Check the DoNotWait field. If it is FALSE you have to wait for the
signals in the WaitMask field (plus your own signals if you like).
If any of the signals in WaitMask are received or DoNotWait was not FALSE
you have to call rtReqHandlerA() and check its return value for one of
the following values:
CALL_HANDLER - Check DoNotWait again, Wait() if you have to
and call rtReqHandlerA() again. In other words, loop.
everything else - normal return value, requester has finished. This
return value will be the same as if the requester
had run normally.
You must pass the signals you received to rtReqHandlerA().
NOTE: if you want to wait for your own signals do not do so if
DoNotWait is TRUE. Call rtReqHandlerA() and if you must know
if one of your signals arrived use SetSignal() to find this out.
If you are waiting for a message to arrive at a message port you
can simple call GetMsg and check if it is non-null.
DoNotWait will naturally only be TRUE when it absolutely,
positively has to be. A multitasking machine as the Amiga should
use Wait() as much as possible.
This is an example of a "requester loop":
...
struct rtHandlerInfo *hinfo;
ULONG ret, mymask, sigs;
...
/* calculate our mask */
mymask = 1 << win->UserPort->mp_SigBit;
/* We use the RT_ReqHandler tag to cause the requester to return
after initializing.
Check the return value to see if this setup went ok. */
if (rtFontRequest (req, "Font", RT_ReqHandler, &hinfo, TAG_END)
== CALL_HANDLER) {
do {
/* Wait() if we can */
if (!hinfo->DoNotWait)
sigs = Wait (hinfo->WaitMask | mymask);
/* check our own message port */
while (msg = GetMsg (win->UserPort)) {
...
/* here we handle messages received at our windows IDCMP ...
port */
...
}
/* let the requester do its thing (remember to pass 'sigs') */
ret = rtReqHandler (hinfo, sigs, TAG_END);
/* continue this loop as long as the requester is up */
} while (ret == CALL_HANDLER)
/* when we get here we know the requester has finished, 'ret'
is the return code. */
...
}
else notify ("Error opening requester!");
...
INPUTS
handlerinfo - pointer to handler info structure initialized by using
the RT_ReqHandler tag when calling a requester function.
sigs - the signals received by previous wait, will be ignored if
hinfo->DoNotWait was TRUE.
taglist - pointer to a TagItem array.
TAGS
RTRH_EndRequest - supplying this tag will end the requester. The return
code from rtReqHandlerA() will _not_ be CALL_HANDLER,
but the requester return code. If the tagdata of this
tag is REQ_CANCEL the requester will be canceled, if it
is REQ_OK the requester will be ok-ed.
In case of an EZRequest tagdata should be the return
code of the requester (TRUE, FALSE or 2,3,4,...).
RESULT
ret - CALL_HANDLER if you have to call rtReqHandlerA() again,
or the normal return value from the requester.
BUGS
none known
SEE ALSO
rtEZRequest() (RT_ReqHandler explanation)
reqtools.library/rtScreenToFrontSafely reqtools.library/rtScreenToFrontSafely
NAME rtScreenToFrontSafely()
rtScreenToFrontSafely (screen);
void rtScreenToFrontSafely (struct Screen *);
A0
DESCRIPTION
Brings the specified screen to the front of the display, but only after
checking it is still in the list of currently open screens.
This function can be used to bring a screen back to the front of the
display after bringing another screen to the front. If the first screen
closed while you where busy it is harmless to call this function, unlike
calling the normal ScreenToFront().
INPUTS
screen - pointer to the screen.
RESULT
none
NOTE
This function is for the advanced reqtools user.
BUGS
none known
SEE ALSO
intuition.library/ScreenToFront()
reqtools.library/rtSetReqPosition reqtools.library/rtSetReqPosition
NAME rtSetReqPosition()
rtSetReqPosition (reqpos, newwindow, screen, window);
void rtSetReqPosition
(ULONG, struct NewWindow *, struct Screen *, struct Window *);
D0 A0 A1 A2
DESCRIPTION
Sets newwindow->LeftEdge and newwindow->TopEdge according to reqpos.
Except for the left- and topedge 'newwindow' must already be completely
initialized.
The newwindow->LeftEdge and newwindow->TopEdge already in the NewWindow
structure will be used as offsets to the requested position. If you'd
like a window at position (25,18) from the top left of the screen you
would fill newwindow->LeftEdge with 25, newwindow->TopEdge with 18 and
call rtSetReqPosition() with reqpos equal to REQPOS_TOPLEFTSCR.
Don't forget to make sure newwindow->LeftEdge and newwindow->TopEdge
are 0 if you don't want to offset your window.
In case of REQPOS_POINTER you can use them to point to your window's
hotspot, where the pointer should point. If you call rtSetReqPosition()
with the left- and topedge equal to 0 you'd get a window appearing with
its top- and leftedge equal to the current pointer position.
Note that the screen pointer may _NOT_ be NULL. If you have your own
window open you can supply yourwindow->WScreen to this function.
The window pointer is only required if reqpos is REQPOS_CENTERWIN or
REQPOS_TOPLEFTWIN. Even in this case you may call rtSetReqPosition()
with a NULL window pointer. The positions will simply fall back to
REQPOS_CENTERSCR and REQPOS_TOPLEFTSCR respectively.
INPUTS
reqpos - one of the REQPOS_... constants usable with RT_ReqPos.
newwindow - pointer to your (already initialized) NewWindow structure.
screen - pointer to screen the requester will appear on.
window - pointer to parent window or NULL.
RESULT
none
NOTE
This function is for the advanced reqtools user.
BUGS
none known
SEE ALSO
RT_ReqPos tag
reqtools.library/rtSetWaitPointer reqtools.library/rtSetWaitPointer
NAME rtSetWaitPointer()
rtSetWaitPointer (window);
void rtSetWaitPointer (struct Window *);
A0
DESCRIPTION
Change the window's pointer image to that of a wait pointer. Call this
function whenever your program will be busy doing something for a lengthy
period of time.
It is recomended you call this function before calling any of the
requester functions. This way if the user clicks in your window he will
know he must respond to the requester before doing anything else. See
also the RT_WaitPointer tag for an automatic way of setting the wait
pointer.
INPUTS
window - pointer to the window to receive the wait pointer.
RESULT
none
NOTE
The wait pointer will look exactly like the standard Workbench 2.0
wait pointer. In combination with PointerX or, even better, ClockTick
the handle will turn.
BUGS
none known
SEE ALSO
reqtools.library/rtSpread reqtools.library/rtSpread
NAME rtSpread()
rtSpread (posarray, sizearray, totalsize, min, max, num);
void rtSpread (ULONG *, ULONG *, ULONG, ULONG, ULONG, ULONG);
A0 A1 D0 D1 D2 D3
DESCRIPTION
Evenly spread a number of objects over a certain length.
Primary use is for arrangement of gadgets in a window.
Example:
'sizearray' holds following values: 4, 6, 4, 2 and 8,
'totalsize' is 24 (= 4 + 6 + 4 + 2 + 8),
'min' is 3, 'max' is 43,
and finally, 'num' is 5.
After calling rtSpread() 'posarray' would hold the following
values: 3, 11, 19, 26 and 31.
My attempt at a visual representation:
| |
| | | |
| OOOO OOOOOO OOOO OO OOOOOOOO |
| | | |
| 1 1 2 2 3 3 4 4
0----5----0----5----0----5----0----5----0----5
INPUTS
posarray - pointer to array to be filled with positions.
sizearray - pointer to array of sizes.
totalsize - total size of all objects (sum of all values in sizearray).
min - first position to use.
max - last position, first _NOT_ to use.
num - number of objects (size of posarray and sizearray).
RESULT
none
NOTE
This function is for the advanced reqtools user.
BUGS
none known
SEE ALSO
